Mailing Lists (XM Subscribers)¶

The methods in the MailingList module give you the ability to create create new mailing lists, delete mailing lists, list all of the available mailing lists to your user account, get a Mailing List’s information, rename a Mailing List, list all of the contacts in a mailing list, and create a new contact within a mailing list.

Create a Mailing List¶

MailingList.create_list(name=None)¶

This method will create a mailing list in the XM Directory for the your specified user’s account.

Parameters: list_name – the name of the list to be created.
Returns: tuple containing the list_name and the list’s new id

Example Implementation¶

Here is an example on how to implement the create_list() method. We will create a new mailing list called ‘MyNewMailingList’ that will be available to your specific user’s account.

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.XM import MailingList

#Create an instance
m = MailingList()

#Call the method
m.create_list(name='MyNewMailingList')

This will return a tuple containing the new mailing list’s name, and the Mailing List ID associated with the new Mailing List.

('MyNewMailingList', 'CG_FakeMailingListID')

List the Mailing Lists Available to your Account¶

MailingList.list_lists(page_size=100, url=None)¶

This method lists all the mailing lists in the directory for the specified user token. You won’t typically need to adjust the pre-defined parameters.

Parameters

page_size (int) – The number of mailing lists to return per call.
url (string) – The url parameter is used to hold the next page url when itterating.

Returns

A Pandas DataFrame

Example Implementation¶

Here is an example on how to implement the list_lists() method. Let’s say that we want to pull in the information from 2 of our Mailing Lists at the start of the list of Mailing Lists. Thus, we set our offset to 0, and the page_size to 2. Let’s say that we also want this to be returned as a Pandas DataFrame, so we pass True to the ‘to_df’ parameter (this is the Default Behavior)

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.XM import MailingList

#Create an instance
m = MailingList()

#Call the method
m.list_lists(page_size=2, offset=0, to_df=True)

This method when implemented and the argument passed to the parameter ‘to_df’ is True, will return a Pandas DataFrame that will look like the following.

           mailingListId               name         ownerId       lastModifiedDate         creationDate contactCount
0  CG_FakeMailingListID1  MyNewMailingList1  UR_FakeUserID1    2017-03-04 14:22:36  2017-02-30 21:32:36          100
1  CG_FakeMailingListID2  MyNewMailingList2  UR_FakeUserID1    2018-05-30 21:32:36  2018-02-15 21:32:31           10

Get the Information about a Mailing List¶

MailingList.get_list(mailing_list=None)¶

This function gets the list specfied by the mailing list param and returns the list members.

Parameters: mailing_list (str) – Your mailing list id that you are interested in getting information on.
Returns: A Pandas DataFrame

Example Implementation¶

The get list method gives you the ability to get the same information about a Mailing List as you would receive from the list_lists() method, except it is for a singular Mailing List.

::

#Setup your Credentials, if not already done. #You only have to do this once.

#Import the module from QualtricsAPI.XM import MailingList

#Create an instance m = MailingList()

#Call the method m.get_list(mailing_list=’CG_FakeMailingListID’)

This method will return a Pandas DataFrame containing information specific to the mailing list that was passed.

           mailingListId               name         ownerId      lastModifiedDate         creationDate contactCount
0  CG_FakeMailingListID1  MyNewMailingList1  UR_FakeUserID1   2018-05-30 21:32:36  2018-02-15 21:32:31          100

Rename a Mailing List¶

MailingList.rename_list(mailing_list=None, name=None)¶

This method takes an existing mailing list name and updates it to reflect the name defined in the name method.

Parameters

mailing_list (str) – Your mailing list id that you are interested in renaming.
name (str) – The new name for the mailing list.

Returns

A string confirming that you successfully renamed the list.

Example Implementation¶

The rename_list method gives you the ability to rename one of your Mailing Lists. Here we will rename our mailing list with the ID ‘CG_FakeMailingListID’, and rename it to ‘NewNamedMList’.

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.XM import MailingList

#Create an instance
m = MailingList()

#Call the method
m.rename_list(mailing_list='CG_FakeMailingListID', name='NewNamedMList')

If you have successfully renamed the mailing list, you will be returned the following message.

'Your mailing list "CG_FakeMailingListID" has been renamed to "NewNamedMList" in the XM Directory.'

Delete a Mailing List¶

MailingList.delete_list(mailing_list=None)¶

This method will delete the specified mailing list from the given users XM Directory.

Parameters: mailing_list (str) – Your mailing list id that you are interested in deleting.
Returns: A string confirming that you successfully deleted the list.

Warning

Once deleted this cannot be undone, be sure that you want to implement this!

Example Implementation¶

The delete_list method gives you the ability to delete one of your Mailing Lists. Here we will delete the mailing list with the ID ‘CG_FakeMailingListID’. We simply pass the ID of the mailing list to the method, and the associated list will be deleted.

::

#Setup your Credentials, if not already done. #You only have to do this once.

#Import the module from QualtricsAPI.XM import MailingList

#Create an instance m = MailingList()

#Call the method m.delete_list(mailing_list=’CG_FakeMailingListID’)

If you have successfully deleted the mailing list, you will be returned the following message.

'Your mailing list "CG_FakeMailingListID" has been deleted from the XM Directory.'

List the Contacts in a Mailing List¶

MailingList.list_contacts(mailing_list=None, page_size=500, url=None)¶

This method creates a pandas DataFrame of all the contacts information within the defined mailing list.

Parameters

mailing_list (str) – the mailing list id
url – the url for a single contact page (typically this doesn’t not need to be changed.)
page_size (int) – The number of contacts in the mailing list to return per call.

Returns

A Pandas DataFrame

Example Implementation¶

In this example lets say that we want to print out the first two contacts within our mailing list with the ID, ‘CG_FakeMailingListID’ and we want to return the information in a pandas DataFrame.

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.XM import MailingList

#Create an instance
m = MailingList()

#Call the method
m.list_contacts(mailing_list='CG_FakeMailingListID', page_size=2, offset=0, to_df=True)

When called you will return a DataFrame that will look like the one below.

           contact_id   first_name last_name                       email phone unsubscribed  language external_ref
0  CID_FakeContactID1         John      Snow     'therealking@email.com'  None        False      'en'         None
1  CID_FakeContactID2         Bran     Stark          'b.stark@fake.net'  None        False      None         None

Create a Contact in a Mailing List¶

Warning

When you create a contact using the create_contact_in_list method, you will also create a record in the XM Directory. This process can lead to duplications of contacts within your XM Directory. Refer to the Manage Directory Duplicates page of the Qualtrics Documentation.

MailingList.create_contact_in_list(mailing_list=None, first_name='', email='', unsubscribed=False, language='en', external_ref='null', phone='null', last_name='null', metadata={})¶

This method creates contacts in the specified mailing list. It is important to remember here that whenever you create a contact in a mailing list, you are also creating that contact in the XMDirectory. Once created 2 seperate IDs are created for the contact. The ContactID is the reference for the contact in the XMDirectory, and the Contact Lookup ID is the reference of the contact in the Mailing List.

Parameters

mailing_list (str) – The mailing list id for the list that you want to add the contact too.
first_name (str) – The new contact’s first name.
last_name (str) – The new contact’s last name.
email (str) – The new contact’s email.
phone – The new contact’s phone number.
external_ref (str) – The new contact’s external reference.
unsubscribed – This parameter denotes whether the new contact is unsubscribed from surveys (Default: False).
language (str) – The language prefered by the new contact (Default: English)
metadata (dict) – Any relevant contact metadata.

Tyoe phone

str

Returns

the contact id (contact_id) in XMDirectory, and the contact id (contact_list_id) in the mailing list.

Example Implementation¶

Here we will learn how to create a new contact within a specific mailing list. Let’s say that we want to create a contact named John Smith, in our mailing list with the ID ‘CG_FakeMailingListID’. We pass all of the parameters that we deem necessary to the John Smith, and then create a record of him in the mailing list (and implicitly in the XMDirectory).

#Setup your Credentials, if not already done.
#You only have to do this once.

#Import the module
from QualtricsAPI.XM import MailingList

#Create an instance
m = MailingList()

#Call the method
m.create_contact_in_list(mailing_list='CG_FakeMailingListID', first_name='John', last_name='Snow', email='therealking@email.com', phone=None, language="en")

If successful, you will be returned a tuple containing John Snow’s new contact_id (ie. the reference in the XMDirectory) and his contact_list_id (i.e. the reference in the specified Mailing List)

('CID_FakeContactID','')